Base URL: https://data.outlearn.com/api/v1

Authentication

All API v1 endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <api-key>

The API key is linked to a specific Agent and Account. All requests are automatically scoped to that agent's account.

Response Formats

Resource

{
  "data": { ... }
}

Collection

{
  "data": [ ... ],
  "pagination": {
    "cursor": "eyJpZCI6NDJ9",
    "has_more": true
  }
}

Error

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": { "field": ["error message"] }
  }
}

Pagination

All collection endpoints use cursor-based (keyset) pagination.

The response pagination object contains:

• cursor — Pass this value as the cursor query parameter to fetch the next page. null when no more results.
• has_more — true if more results exist beyond this page.

Error Codes

Agents

List Agents

GET /api/v1/agents

Returns the agent associated with the authenticated API key.

Query Parameters

Response 200 OK

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Support Bot",
      "description": "Handles customer support inquiries",
      "status": "active",
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-02-20T14:15:00.000Z"
    }
  ],
  "pagination": {
    "cursor": null,
    "has_more": false
  }
}

Retrieve Agent

GET /api/v1/agents/{id}

Path Parameters

Response 200 OK

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Support Bot",
    "description": "Handles customer support inquiries",
    "status": "active",
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-02-20T14:15:00.000Z"
  }
}

Errors

Update Agent

PATCH /api/v1/agents/{id}

Path Parameters

Request Body

Request Example

{
  "name": "Updated Support Bot",
  "status": "inactive"
}

Response 200 OK

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Updated Support Bot",
    "description": "Handles customer support inquiries",
    "status": "inactive",
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-03-14T09:00:00.000Z"
  }
}

Errors

Contacts

List Contacts

GET /api/v1/contacts

Returns contacts scoped to the authenticated account.

Query Parameters

Response 200 OK

{
  "data": [
    {
      "id": 1,
      "name": "Jane Smith",
      "email": "jane@example.com",
      "guest": false,
      "metadata": {
        "company": "Acme Corp",
        "plan": "enterprise"
      },
      "created_at": "2026-02-01T08:00:00.000Z",
      "updated_at": "2026-03-10T12:30:00.000Z"
    }
  ],
  "pagination": {
    "cursor": "eyJpZCI6MX0",
    "has_more": false
  }
}

Response Fields

Retrieve Contact

GET /api/v1/contacts/{id}

Path Parameters

Response 200 OK

{
  "data": {
    "id": 1,
    "name": "Jane Smith",
    "email": "jane@example.com",
    "guest": false,
    "metadata": { "company": "Acme Corp" },
    "created_at": "2026-02-01T08:00:00.000Z",
    "updated_at": "2026-03-10T12:30:00.000Z"
  }
}

Errors

Create or Find Contact

POST /api/v1/contacts

Uses a find-or-create pattern. If a contact with the given email already exists in the account, it is returned (and updated with any provided fields). Otherwise a new contact is created.

If no email is provided, an anonymous guest contact is created.

Request Body

Request Example

{
  "email": "jane@example.com",
  "name": "Jane Smith",
  "metadata": {
    "company": "Acme Corp",
    "plan": "enterprise"
  }
}

Response — New Contact 201 Created

{
  "data": {
    "id": 2,
    "name": "Jane Smith",
    "email": "jane@example.com",
    "guest": false,
    "metadata": { "company": "Acme Corp", "plan": "enterprise" },
    "created_at": "2026-03-14T09:00:00.000Z",
    "updated_at": "2026-03-14T09:00:00.000Z"
  },
  "created": true
}

Response — Existing Contact 200 OK

{
  "data": {
    "id": 1,
    "name": "Jane Smith",
    "email": "jane@example.com",
    "guest": false,
    "metadata": { "company": "Acme Corp", "plan": "enterprise" },
    "created_at": "2026-02-01T08:00:00.000Z",
    "updated_at": "2026-03-14T09:00:00.000Z"
  },
  "created": false
}

Update Contact

PATCH /api/v1/contacts/{id}

Path Parameters

Request Body

Request Example

{
  "name": "Jane Doe",
  "metadata": {
    "plan": "pro",
    "company": null
  }
}

Response 200 OK

Returns the updated contact resource.

Errors

Conversations

List Conversations

GET /api/v1/conversations

Returns conversations scoped to the authenticated account.

Query Parameters

Response 200 OK

{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "contact_id": 1,
      "status": "active",
      "metadata": { "source": "widget" },
      "ended_at": null,
      "created_at": "2026-03-14T08:00:00.000Z",
      "updated_at": "2026-03-14T08:30:00.000Z"
    }
  ],
  "pagination": {
    "cursor": null,
    "has_more": false
  }
}

Response Fields

Retrieve Conversation

GET /api/v1/conversations/{id}

Path Parameters

Response 200 OK

{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "contact_id": 1,
    "status": "active",
    "metadata": { "source": "widget" },
    "ended_at": null,
    "created_at": "2026-03-14T08:00:00.000Z",
    "updated_at": "2026-03-14T08:30:00.000Z"
  }
}

Errors

Create Conversation

POST /api/v1/conversations

Creates a new conversation for a contact.

Request Body

Request Example

{
  "contact_id": 1,
  "metadata": {
    "source": "api",
    "session": "abc123"
  }
}

Response 201 Created

{
  "data": {
    "id": "b3d7e9a2-1c4f-4a8e-9b6d-2f5e8c1a3d7b",
    "contact_id": 1,
    "status": "active",
    "metadata": { "source": "api", "session": "abc123" },
    "ended_at": null,
    "created_at": "2026-03-14T09:00:00.000Z",
    "updated_at": "2026-03-14T09:00:00.000Z"
  }
}

Errors

End Conversation

POST /api/v1/conversations/{id}/end

Closes an active conversation. Once ended, no new messages can be added.

Path Parameters

Response 200 OK

{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "contact_id": 1,
    "status": "ended",
    "metadata": { "source": "widget" },
    "ended_at": "2026-03-14T10:00:00.000Z",
    "created_at": "2026-03-14T08:00:00.000Z",
    "updated_at": "2026-03-14T10:00:00.000Z"
  }
}

Errors

Messages

List Messages

GET /api/v1/conversations/{conversation_id}/messages

Returns user and assistant messages in a conversation (internal system messages are excluded).

Path Parameters

Query Parameters

Response 200 OK

{
  "data": [
    {
      "id": 101,
      "role": "user",
      "content": "What is your return policy?",
      "created_at": "2026-03-14T09:00:00.000Z"
    },
    {
      "id": 102,
      "role": "assistant",
      "content": "Our return policy allows returns within 30 days of purchase...",
      "created_at": "2026-03-14T09:00:05.000Z"
    }
  ],
  "pagination": {
    "cursor": null,
    "has_more": false
  }
}

Response Fields

Errors

Create Message

POST /api/v1/conversations/{conversation_id}/messages

Sends a user message and generates an AI assistant response. Supports both synchronous and streaming modes.

Path Parameters

Request Body

Request Example

{
  "content": "What is your return policy?",
  "stream": false
}

Synchronous Response (stream: false)

Response 201 Created

{
  "data": {
    "user_message": {
      "id": 101,
      "role": "user",
      "content": "What is your return policy?",
      "created_at": "2026-03-14T09:00:00.000Z"
    },
    "assistant_message": {
      "id": 102,
      "role": "assistant",
      "content": "Our return policy allows returns within 30 days of purchase...",
      "created_at": "2026-03-14T09:00:05.000Z"
    }
  }
}

Streaming Response (stream: true)

Response 200 OK Content-Type: text/event-stream

The response is delivered as Server-Sent Events (SSE). Events are sent in this order:

Stream Example

event: message.created
data: {"id":101,"role":"user","content":"What is your return policy?","created_at":"2026-03-14T09:00:00.000Z"}

event: stream.start
data: {"message_id":102,"role":"assistant"}

event: stream.delta
data: {"delta":"Our return "}

event: stream.delta
data: {"delta":"policy allows "}

event: stream.delta
data: {"delta":"returns within 30 days of purchase..."}

event: stream.end
data: {"message_id":102,"content":"Our return policy allows returns within 30 days of purchase...","created_at":"2026-03-14T09:00:05.000Z"}

Errors